<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<!-- Copyright 1997 The Open Group, All Rights Reserved -->
<title>sigaltstack</title>
</head><body bgcolor=white>
<center>
<font size=2>
The Single UNIX &reg; Specification, Version 2<br>
Copyright &copy; 1997 The Open Group

</font></center><hr size=2 noshade>
<h4><a name = "tag_000_008_597">&nbsp;</a>NAME</h4><blockquote>
sigaltstack - set and/or get signal alternate stack context.
</blockquote><h4><a name = "tag_000_008_598">&nbsp;</a>SYNOPSIS</h4><blockquote>
<pre><code>

#include &lt;<a href="signal.h.html">signal.h</a>&gt;

int sigaltstack(const stack_t *<i>ss</i>, stack_t *<i>oss</i>);
</code>
</pre>
</blockquote><h4><a name = "tag_000_008_599">&nbsp;</a>DESCRIPTION</h4><blockquote>
The
<i>sigaltstack()</i>
function allows a process to define
and examine the state of an alternate stack for signal handlers.
Signals that have been explicitly declared to execute on the alternate
stack will be delivered on the alternate stack.
<p>
If <i>ss</i> is not a null pointer, it points to a <b>stack_t</b> structure
that specifies the alternate signal stack that will take effect upon return
from
<i>sigaltstack()</i>.
The <b>ss_flags</b> member specifies the new stack state.  If it is set to
SS_DISABLE, the stack is disabled and <b>ss_sp</b> and <b>ss_size</b> are
ignored.  Otherwise the stack will be enabled, and the <b>ss_sp</b> and
<b>ss_size</b> members specify the new address and size of the stack.
<p>
The range of addresses starting at <b>ss_sp</b>, up to but not including
<b>ss_sp</b>+<b>ss_size</b>, is available to the implementation for use as
the stack.  This interface makes no assumptions regarding which end is the
stack base and in which direction the stack grows as items are pushed.
<p>
If <i>oss</i> is not a null pointer, on successful completion it
will point to a <b>stack_t</b> structure that specifies the alternate signal
stack that was in effect prior to the call to
<i>sigaltstack()</i>.
The <b>ss_sp</b> and <b>ss_size</b> members specify the address and size of
that stack.  The <b>ss_flags</b> member specifies the stack's state, and may
contain one of the following values:
<dl compact>

<dt>SS_ONSTACK<dd>
The process is currently executing on the alternate signal stack.  Attempts to
modify the alternate signal stack while the process is executing on it fails.
This flag must not be modified by processes.

<dt>SS_DISABLE<dd>
The alternate signal stack is currently disabled.

</dl>
<p>
The value SIGSTKSZ is a system default specifying the number of bytes that
would be used to cover the usual case when manually allocating an alternate
stack area.  The value MINSIGSTKSZ is defined to be the minimum stack size for
a signal handler.  In computing an alternate stack size, a program should add
that amount to its stack requirements to allow for the system implementation
overhead.  The constants SS_ONSTACK, SS_DISABLE, SIGSTKSZ, and MINSIGSTKSZ are
defined in
<i><a href="signal.h.html">&lt;signal.h&gt;</a></i>.
<p>
After a successful call to one of the
<i>exec</i>
functions, there are no alternate signal stacks in the new process image.
<p>
In some implementations, a signal (whether or not indicated to execute on the
alternate stack) will always execute on the alternate stack if it is delivered
while another signal is being caught using the alternate stack.
<p>
Use of this function by library threads that are not bound to
kernel-scheduled entities results in undefined behaviour.
</blockquote><h4><a name = "tag_000_008_600">&nbsp;</a>RETURN VALUE</h4><blockquote>
Upon successful completion,
<i>sigaltstack()</i>
returns 0.  Otherwise, it returns -1 and sets <i>errno</i> to indicate the
error.
<br>
</blockquote><h4><a name = "tag_000_008_601">&nbsp;</a>ERRORS</h4><blockquote>
The
<i>sigaltstack()</i>
function will fail if:
<dl compact>

<dt>[EINVAL]<dd>
The <i>ss</i> argument is not a null pointer, and the <b>ss_flags</b> member
pointed to by <i>ss</i> contains flags other than SS_DISABLE.

<dt>[ENOMEM]<dd>
The size of the alternate stack area is less than MINSIGSTKSZ.

<dt>[EPERM]<dd>
An attempt was made to modify an active stack.

</dl>
</blockquote><h4><a name = "tag_000_008_602">&nbsp;</a>EXAMPLES</h4><blockquote>
None.
</blockquote><h4><a name = "tag_000_008_603">&nbsp;</a>APPLICATION USAGE</h4><blockquote>
The following code fragment illustrates a method for allocating
memory for an alternate stack:
<pre>
<code>
if ((sigstk.ss_sp = malloc(SIGSTKSZ)) == NULL)
    /* error return */
sigstk.ss_size = SIGSTKSZ;
sigstk.ss_flags = 0;
if (sigaltstack(&amp;sigstk,(stack_t *)0) &lt; 0)
    perror("sigaltstack");
</code>
</pre>
On some implementations, stack space is automatically extended as needed.  On
those implementations, automatic extension is typically not available for an
alternate stack.  If the stack overflows, the behaviour is undefined.
</blockquote><h4><a name = "tag_000_008_604">&nbsp;</a>FUTURE DIRECTIONS</h4><blockquote>
None.
</blockquote><h4><a name = "tag_000_008_605">&nbsp;</a>SEE ALSO</h4><blockquote>
<i><a href="sigaction.html">sigaction()</a></i>,
<i><a href="sigsetjmp.html">sigsetjmp()</a></i>,
<i><a href="signal.h.html">&lt;signal.h&gt;</a></i>.
</blockquote><hr size=2 noshade>
<center><font size=2>
UNIX &reg; is a registered Trademark of The Open Group.<br>
Copyright &copy; 1997 The Open Group
<br> [ <a href="../index.html">Main Index</a> | <a href="../xshix.html">XSH</a> | <a href="../xcuix.html">XCU</a> | <a href="../xbdix.html">XBD</a> | <a href="../cursesix.html">XCURSES</a> | <a href="../xnsix.html">XNS</a> ]

</font></center><hr size=2 noshade>
</body></html>
